PER.rover.control
Class RoverController

java.lang.Object
  extended byPER.rover.control.RoverController
Direct Known Subclasses:
Rover

public class RoverController
extends java.lang.Object

Allows communication with and control of the robot. Generally programs should access the functions in RoverController through its subclass, Rover.

For all of the functions in this class that set the motor speeds, the speed should be a number in the range of [-255, 255]. On the cerebellum this is represented by an 8-bit number and a sign bit. This speed is the pulse width that the motors are getting. If the pulse is less than 50% duty cycle, the motors won't turn on. Therefore, if you want the rover to go backwards, set the speed to be between -129 and -255. If you want the rover to go forwards, set the speed to be between 129 and 255. The motor changes speed roughly linearly withing these ranges. Speeds outside of the range [-255, 255] are capped.


Field Summary
 RoverState highLevelState
          This instance of the state is updated only by goTo, turnTo, killHighLevel, and updateHighLevel.
static int READ_TIMEOUT
          The time in ms of how long to wait for the rover to respond.
 ReceiveThread receive
          This class contains images sent back during DriveTo and TurnTo as well as tracking data.
 Reliagram reliagram
           
 RoverState state
          This instance of the state is updated whenever you call a simple command.
 
Constructor Summary
RoverController()
          Creates a new RoverController
 
Method Summary
 boolean closeComm()
          Closes communication with the rover.
static int compareVersion(java.lang.String version1, java.lang.String version2)
          Compares two version strings.
 boolean crab(int speed, int angle)
          Moves the rover in a straight line at the specified angle.
 java.lang.String getCalibration()
          This funciton is useful if you want to see the servo calibration on the rover.
 int[] getCameraProperties()
          Gets information on the state of the camera.
 int getDriveCalibration()
          Loads the calibration file from the rover and returns the drive adjustment value.
 boolean getMean(boolean stream)
          Gets the mean for the red, green and blue channels.
 java.lang.String getScanList()
          This funciton is useful if you want to see the scan calibration on the rover.
 int getTurnCalibration()
          Loads the calibration file from the rover and returns the turn adjustment value.
 java.lang.String getVersion()
          Gets the version of the code running on the Stargate as a String.
 boolean goTo(int dist, int angle)
          This command starts the rover to go the specified distance while driving at the specified angle.
 boolean goTo(int dist, int angle, byte safetyLevel, boolean takePics)
          This command starts the rover to go the specified distance while driving at the specified angle.
 boolean headMove(boolean doPan, int pan, boolean doTilt, int tilt)
          This function is just like the look command, but you can specify whether you want to move ther servo or not.
 boolean initComm(java.lang.String ipaddr)
          Initializes the communication with the robot but does not check that the rover is on or that it is responding.
 boolean initRobot()
          Initalizes the rover; centers all of the servos and sets wheel velocities to zero.
 boolean isConnected()
          Returns true if connected to a robot.
 boolean killHighLevel()
          This function will kill any currently running turnTo, goTo or scan.
 boolean killRobot()
          Kills anything the rover is doing by calling initRobot.
 boolean look(int pan, int tilt)
          Moves the pan and tilt on the PER.
 boolean quadTurn(int speed, int radius)
          This function has the rover move and rotate about the point (0, radius) in the rover's reference frame.
 boolean refresh()
          This command refreshes the state of the robot.
 int[] scan(int tilt, int minPan, int maxPan, int step)
          Scans the area around where the rover is.
 boolean setAll(int mask, int rightMotor, int leftMotor, int frontLeftServo, int frontRightServo, int backRightServo, int backLeftServo, int pan, int tilt)
          Allows you to directly set the positions of the motors and servos.
 boolean setCalibration(java.lang.String cal)
          Sets the calibration file on the robot.
 boolean setLight(boolean on)
          This function allows you to turn the UV light on the rover on or off.
 boolean setPan(int pan)
          This command is just like look, but only sets the pan.
 boolean setScanList(java.lang.String cal)
          This funciton sets the scan calibration on the rover.
 boolean setTilt(int tilt)
          This command is just like look, but only sets the tilt.
 boolean spin(int speed)
          Turns the rover about its center point.
 boolean startMotionDetection()
          Starts the rover detection motion.
 boolean startTrack(int minY, int maxY, int minU, int maxU, int minV, int maxV)
          Starts the rover tracking an object.
 boolean startTrack(int minY, int maxY, int minU, int maxU, int minV, int maxV, int trackMethod, boolean movePan, boolean moveTilt, int driveMethod)
          Starts the rover tracking an object.
 boolean stopStreaming()
          Stops the rover's camera commands that stream which include getMean and tracking.
 java.awt.image.BufferedImage takePicture(int pan, int tilt, int width, int height)
          This function is the same as the other takePicture function, but has the UV light off.
 java.awt.image.BufferedImage takePicture(int pan, int tilt, int width, int height, boolean lightUV)
          Tries to take a picture.
 byte[] takeRawPicture(int pan, int tilt, int width, int height)
          This function returns the raw YUV that the camera returns.
 java.awt.image.BufferedImage takeRecentPicture()
          Gives you the most recent picture that was taken by the rover.
 boolean turnTo(int degrees)
          This command starts the rover to turn the specified number of degrees.
 boolean turnTo(int degrees, boolean takePics)
          This command starts the rover to turn the specified number of degrees.
 boolean updateHighLevel()
          This function is intended for use in PER.rover.DriveToAction and PER.rover.TurnToAction.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

state

public RoverState state
This instance of the state is updated whenever you call a simple command.


highLevelState

public RoverState highLevelState
This instance of the state is updated only by goTo, turnTo, killHighLevel, and updateHighLevel.


receive

public ReceiveThread receive
This class contains images sent back during DriveTo and TurnTo as well as tracking data.


reliagram

public Reliagram reliagram

READ_TIMEOUT

public static final int READ_TIMEOUT
The time in ms of how long to wait for the rover to respond.

See Also:
Constant Field Values
Constructor Detail

RoverController

public RoverController()
Creates a new RoverController

Method Detail

initComm

public boolean initComm(java.lang.String ipaddr)
Initializes the communication with the robot but does not check that the rover is on or that it is responding.

Parameters:
ipaddr - An IP address or hostname.
Returns:
This command will only return false if you specify a hostname that cannot be resolved.

closeComm

public boolean closeComm()
Closes communication with the rover. Calling this function allows memory being used by the communication functions to be freed.

Returns:
true if you are connected, false if you aren't.

isConnected

public boolean isConnected()
Returns true if connected to a robot.


initRobot

public boolean initRobot()
Initalizes the rover; centers all of the servos and sets wheel velocities to zero.

Returns:
false if not connected to a rover or the rover can not be initialized

killRobot

public boolean killRobot()
Kills anything the rover is doing by calling initRobot.

See Also:
initRobot()

takePicture

public java.awt.image.BufferedImage takePicture(int pan,
                                                int tilt,
                                                int width,
                                                int height,
                                                boolean lightUV)
Tries to take a picture. With the creative web cam, 320x240 is the best resolution to take pictures at. Getting the image from the camera only takes about 300ms. If you go to a higher resolution, it will take the middle pixels from a 640x480 image. For example, at 352x288, the field of view is smaller than at 320x240 because of the way images are taken. Because of a bug in the driver on the Stayton, all images at 160x120 are corrupted. Upon failure, null is returned and the status code of state is set.

Parameters:
pan - The pan value in degrees at which to take the picture.
tilt - The tilt vale in degrees at which to take the picture.
width - The width of the image in pixels.
height - The hiehgt of the image in pixels.
Returns:
A new BufferedImage upon success.

takePicture

public java.awt.image.BufferedImage takePicture(int pan,
                                                int tilt,
                                                int width,
                                                int height)
This function is the same as the other takePicture function, but has the UV light off.


takeRawPicture

public byte[] takeRawPicture(int pan,
                             int tilt,
                             int width,
                             int height)
This function returns the raw YUV that the camera returns. It has the same parameters as the other functions.


takeRecentPicture

public java.awt.image.BufferedImage takeRecentPicture()
Gives you the most recent picture that was taken by the rover. DriveToAction and TurnToAction take pictures while they are doing the Aciton. Upon failure, null is returned and the status code of state is set.

Returns:
The most recent picture the rover has taken. If it is in the process of taking a picture, that picture is returned.

scan

public int[] scan(int tilt,
                  int minPan,
                  int maxPan,
                  int step)
Scans the area around where the rover is. The scan is done starting with the minPan and increments to maxPan. Scans are done at positions from minPan to maxPan inclusive. Upon failure, null is returned and the status code of state is set.

Parameters:
tilt - The tilt at which the scan is done.
minPan - The pan angle at which the scan starts
maxPan - The pan angle at which the scan ends.
step - The angle difference between successive scan points.
Returns:
An array of the scan points in terms of the range sensing data. There will be (maxPan-minPan+step)/step points in the array.

goTo

public boolean goTo(int dist,
                    int angle)
This command starts the rover to go the specified distance while driving at the specified angle. Use the DriveToAction if you want it to wait for the rover to finish. Using this function, it has safety on so it won't hit things and it will take pictures.

Parameters:
dist - How many centimenters to drive
angle - The angle for the rover to drive at. This angle must be in the range of [-90, 90] or else you will get a BAD_INPUT error.
See Also:
DriveToAction

goTo

public boolean goTo(int dist,
                    int angle,
                    byte safetyLevel,
                    boolean takePics)
This command starts the rover to go the specified distance while driving at the specified angle. Use the DriveToAction if you want it to wait for the rover to finish. Using this function, it has safety on so it won't hit things and it will take pictures. This function will always update the information in highLevelState

Parameters:
dist - How many centimenters to drive
angle - The angle for the rover to drive at. This angle must be in the range of [-90, 90] or else you will get a BAD_INPUT error.
safetyLevel - See constants at top of PER.rover.DriveToAction
See Also:
DriveToAction

turnTo

public boolean turnTo(int degrees,
                      boolean takePics)
This command starts the rover to turn the specified number of degrees. Use the TurnToAction if you want it to wait for the rover to finish. If the angle is not in the range of [-180, 180], the rover will turn the equivalent angle in that range. This function will always update the information in highLevelState

Parameters:
degrees - How many degrees to turn, with positive being to the left
takePics - Whether or not to take pictures while driving.
See Also:
DriveToAction

turnTo

public boolean turnTo(int degrees)
This command starts the rover to turn the specified number of degrees. Use the TurnToAction if you want it to wait for the rover to finish. If the angle is not in the range of [-180, 180], the rover will turn the equivalent angle in that range. This function will always update all information in highLevelState

Parameters:
degrees - How many degrees to turn, with positive being to the left
See Also:
DriveToAction

killHighLevel

public boolean killHighLevel()
This function will kill any currently running turnTo, goTo or scan. If you are using TurnToAction or DriveToAction, you should use their kill() functions. By calling killHighLevel, the action you are killing will return with an error code of KILLED This function will always update the information in highLevelState

Returns:
true if there was something to be killed and it was

updateHighLevel

public boolean updateHighLevel()
This function is intended for use in PER.rover.DriveToAction and PER.rover.TurnToAction. It will return the status of either the currently running action or the last one to run. This function will always update the information in highLevelState

Returns:
true if the update was successful

getDriveCalibration

public int getDriveCalibration()
Loads the calibration file from the rover and returns the drive adjustment value. The drive adjustment value is used by the rover to ensure that goTo commands work the same from rover to rover despite variation in the drive motors. The adjustment value is a percentage. A value below 100 means drive for a shorter time. A value above 100 means drive for a longer time.

Because crab and quadTurn do not make use of the drive calibration, programs that use these commands may want to want to use getDriveCalibration to ensure that the program behaves the same from rover to rover.

This function will only update the status in state in case of error.

Returns:
The drive adjustment value from the rover's calibration file. Returns a default value of 100 if the file can not be loaded or there is an error.

getTurnCalibration

public int getTurnCalibration()
Loads the calibration file from the rover and returns the turn adjustment value. The turn adjustment value is used by the rover to ensure that turnTo commands work the same from rover to rover despite variation in the drive motors. The adjustment value is a percentage. A value below 100 means turn for a shorter time. A value above 100 means turn for a longer time.

Because spin does not make use of the turn calibration, programs that use spin may want to want to use getTurnCalibration to ensure that the program behaves the same from rover to rover.

This function will only update the status in state in case of error.

Returns:
The turn adjustment value from the rover's calibration file. Returns a default value of 100 if the file can not be loaded or there is an error.

getCalibration

public java.lang.String getCalibration()
This funciton is useful if you want to see the servo calibration on the rover. It is used by PER.Calibration. This file contains calibration for the servos and the motors. This function will only update the status in state in case of error.

Returns:
The calibration file from the rover as a string. Its location is /root/rover.cal on the Stargate.

setCalibration

public boolean setCalibration(java.lang.String cal)
Sets the calibration file on the robot. This function is used by PER.Calibration. The file is located at /root/rover.cal on the Stargate. If the calibration is messed up, the rover will not work right. Once you call this function, it replaces the current file on the Stargate and the calibration is immediately changed. This function will always update the information in state

Parameters:
cal - The calibration file as a String.
Returns:
true if this command worked.

getScanList

public java.lang.String getScanList()
This funciton is useful if you want to see the scan calibration on the rover. It is used by PER.Calibration. This function will only update the status in state in case of error.

Returns:
The scan calibration file from the rover as a string. Its location is /root/rover.scan on the Stargate.

setScanList

public boolean setScanList(java.lang.String cal)
This funciton sets the scan calibration on the rover. It is used by PER.Calibration. The file is located at /root/rover.scan on the Stargate. If the scan calibration is messed up, the rover will not scan correctly and may not scan at all if there are no valid lines. Once you call this function, it replaces the current file on the Stargate and the scan calibration is immediately changed. This function will always update the information in state

Parameters:
cal - The scan calibration file as a String.
Returns:
true if this command worked.

look

public boolean look(int pan,
                    int tilt)
Moves the pan and tilt on the PER. This function does not wait for the head servos to reach the desired position. This function will always update the information in state

Parameters:
pan - The pan angle in degrees for the PER to move its head to. This value should be in the range of [-180, 180]. If you choose an angle outside of this range, the pan will be set to the closest valid value. Positive angles are to the left.
tilt - The tilt angle in degrees for the PER to move its head to. This value should be in the range of [-50, 90]. If you choose an angle outside of this range, the tilt will be set to the closest valid value.
Returns:
true if the command worked.

setPan

public boolean setPan(int pan)
This command is just like look, but only sets the pan.

Parameters:
pan - The desired pan angle.
Returns:
true if the command worked.
See Also:
look(int, int)

setTilt

public boolean setTilt(int tilt)
This command is just like look, but only sets the tilt.

Parameters:
tilt - The desired tilt angle.
Returns:
true if the command worked.
See Also:
look(int, int)

refresh

public boolean refresh()
This command refreshes the state of the robot. By calling this function, you will get the most up to date values for the battery voltage, range, etc.

Returns:
true if the command worked.

headMove

public boolean headMove(boolean doPan,
                        int pan,
                        boolean doTilt,
                        int tilt)
This function is just like the look command, but you can specify whether you want to move ther servo or not.


setAll

public boolean setAll(int mask,
                      int rightMotor,
                      int leftMotor,
                      int frontLeftServo,
                      int frontRightServo,
                      int backRightServo,
                      int backLeftServo,
                      int pan,
                      int tilt)
Allows you to directly set the positions of the motors and servos. The motor speeds must be in the range of [-255, 255] and the servos must be in the range of [0, 255] with 0 meaning that the servos are off. The values for the servos are the raw servo values that the cerebellum understands. As an example, if you only want to turn the motors off, but not move the steering servos, call setAll(3, 0, 0, 0, 0, 0, 0, 0, 0); This function will always update the information in state

Parameters:
mask - An 8-bit mask specifying which of these parameters you want to set. 1 is the mask for the rightMotor, 2 for the leftMotor, . . . 128 for the tilt servo.
rightMotor - The motor speed for the right motor.
leftMotor - The motor speed for the left motor.
frontLeftServo - The servo position for the front left servo.
frontRightServo - The servo position for the front right servo.
backRightServo - The servo position for the back right servo.
backLeftServo - The servo position for the back left servo.
pan - The servo postition for the pan servo.
tilt - The servo postition for the tilt servo.

spin

public boolean spin(int speed)
Turns the rover about its center point. A positive speed turns the rover left and a negative speed turns the rover right. This function will always update the information in state

Parameters:
speed - How fast to go - see comments at top of file for more explaination.
Returns:
true if the command worked

crab

public boolean crab(int speed,
                    int angle)
Moves the rover in a straight line at the specified angle. For example, at an angle of 0, it will drive straight. At an angle of 45, it will move forwards and left. An angle of -90 and a positive speed will move the rover to the right. This function will always update the information in state

Parameters:
speed - How fast to go - see comments at top of file for more explaination.
angle - The angle the steering servos are set to. Angles outside of the valid range of [-90, 90] are capped.
Returns:
true if the command worked

quadTurn

public boolean quadTurn(int speed,
                        int radius)
This function has the rover move and rotate about the point (0, radius) in the rover's reference frame. Imaging that the rover is on a grid at (0, 0) and is facing down the x-axis. This function will cause the rover to rotate about the point (0, radius). The special case is that if the radius is 0, the rover will drive straight. You should call spin in that case. This function will always update the information in state

Parameters:
speed - How fast to go - see comments at top of file for more explaination.
radius - The radius to turn around.
Returns:
true if the command worked

setLight

public boolean setLight(boolean on)
This function allows you to turn the UV light on the rover on or off. This function will always update the information in state

Parameters:
on - If true, the light will turn on, if false, the light will turn off.
Returns:
true if the command worked

getVersion

public java.lang.String getVersion()
Gets the version of the code running on the Stargate as a String. More recent versions will return a string with two decimal points, for example "2.0.0"

Returns:
The version number as a String.

compareVersion

public static int compareVersion(java.lang.String version1,
                                 java.lang.String version2)
                          throws java.lang.NumberFormatException
Compares two version strings. It expects the strings to be in a format like the one returned by the stargate, which is "x.x.x" Passing null or improper strings will result in an exception being thrown.

Parameters:
version1 - The first string to compare
version2 - The second string to compare
Returns:
1 if version1 is more recent than version2, 0 if the versions are equal, and -1 if version2 is more recent than version1.
Throws:
java.lang.NumberFormatException

startTrack

public boolean startTrack(int minY,
                          int maxY,
                          int minU,
                          int maxU,
                          int minV,
                          int maxV)
Starts the rover tracking an object. The information the rover sends back is stored in receive. By default, it tracks the largest blob, moving only pan and tilt, and doesn't drive.

Parameters:
minY - The minimum Y value to track.
maxY - The maximum Y value to track.
minU - The minimum U value to track.
maxU - The maximum U value to track.
minV - The minimum V value to track.
maxV - The maximum V value to track.
Returns:
true if starting tracking was successful

stopStreaming

public boolean stopStreaming()
Stops the rover's camera commands that stream which include getMean and tracking. This function will always update the information in state

Returns:
A return value of true imples that that the rover is not currently streaming anything and is ready for new commands. If the rover is currently taking pictures, or a TurnTo or DriveTo needs the head, false will be returned and the rover status will be RESOURCE_CONFLICT.

startTrack

public boolean startTrack(int minY,
                          int maxY,
                          int minU,
                          int maxU,
                          int minV,
                          int maxV,
                          int trackMethod,
                          boolean movePan,
                          boolean moveTilt,
                          int driveMethod)
Starts the rover tracking an object. The information the rover sends back is stored in receive. This function will always update the information in state

Parameters:
minY - The minimum Y value to track.
maxY - The maximum Y value to track.
minU - The minimum U value to track.
maxU - The maximum U value to track.
minV - The minimum V value to track.
maxV - The maximum V value to track.
trackMethod - Controls how the object is tracked. 0=biggest blob
movePan - If set to true, it will move the pan angle to try and center the object tracked.
moveTilt - If set to true, it will move the tilt angle to try and center the object tracked.
driveMethod - Currently not supported.
Returns:
true if starting tracking was successful

getCameraProperties

public int[] getCameraProperties()
Gets information on the state of the camera. Because the camera is set in autogain mode, the brightness will change during use. The other values do not change. With the camera in the rover, a brightness value of 16384 indicates that it is looking at something really bright. If it is looking at something dark or is in a dimly lit room, the brightness will be in the range of 30000-35000.

The function works by calling VIDIOCSPICT and returns the contents of the struct video_picture. This function will only update the status in state in case of error.

Returns:
Upon success an integer array of size 7 is returned containing [brightness, hue, colour, contrast, whiteness, depth, palette]. If a failure occurs, null is returned.

getMean

public boolean getMean(boolean stream)
Gets the mean for the red, green and blue channels. The information the rover sends back is stored in receive. This function will always update the information in state

Parameters:
stream - If set to true, the rover will stream the data back until stopStreaming() is called. If set to false, the rover will send back the current mean values and then quit.
Returns:
true if the command worked

startMotionDetection

public boolean startMotionDetection()
Starts the rover detection motion. The information the rover sends back is stored in receive. This function will always update the information in state

Returns:
true if starting to detect motion was successful